Add HST/tax support and payment reporting with HST aggregation

Studio Settings gains a default HST rate; the rate is frozen onto each
payment at booking and computed against the pre-tax subtotal, with the
total billed as subtotal + tax. The rate is overridable per booking on
My Lessons while unpaid (recomputing the tax amount), comped
registrations are never taxed, and receipts break out subtotal/HST/total.

Builds the payments report (roadmap #8) from us_payments: a monthly
per-instructor view with subtotal, HST collected, and grand-total
aggregation, plus a nonce-protected CSV export via admin-post. Studio
admins see all instructors and can filter; instructors are scoped to
their own rows. The Payment Report menu is gated on export_payments so
instructors (who lack manage_billing) can reach it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/features/payment-reporting.md

@@ -1,49 +1,68 @@
 # Feature: Payment Reporting
 
 ## Overview
-A monthly view of payments per instructor, with a downloadable spreadsheet (CSV) export. The studio admin sees every instructor and can filter; each instructor sees only their own payments. The report is built entirely from `us_payments` — no additional table.
+
+A monthly view of paid payments with **HST aggregation** and a downloadable
+spreadsheet (CSV) export. The studio admin sees every instructor and can filter;
+each instructor sees only their own payments. The report is built entirely from
+`us_payments` — no additional table.
 
 ## Data Source
-Reads `{prefix}us_payments` (see `payments.md`), grouped by calendar month and
-instructor. Each report row joins through to the student and offering for display:
+
+Reads `{prefix}us_payments` (see `payments.md`), filtered to `paid` rows whose
+`paid_at` falls within the selected calendar month, optionally narrowed to one
+instructor. Each report row resolves the student and instructor for display:
 
 | Report Column | Source                                            |
 |---------------|---------------------------------------------------|
-| Date          | `us_payments.paid_at` (falls back to `created_at`) |
+| Date          | `us_payments.paid_at` (date portion)              |
 | Student       | `us_payments.student_id` → display name           |
-| Offering      | registration → `us_offerings.title`               |
+| Instructor    | `us_payments.instructor_id` → display name        |
 | Method        | `us_payments.method`                              |
 | Status        | `us_payments.status`                              |
-| Amount        | `us_payments.amount_cents` / `currency`           |
+| Subtotal      | `us_payments.amount` / `currency`                 |
+| HST           | `us_payments.tax_amount` (with `tax_rate` %)      |
+| Total         | `amount + tax_amount` (`Payment::total()`)        |
 
-Totals are summed over `paid` rows for the selected month.
+Three totals are summed over the selected rows: **subtotal**, **HST collected**
+(the figure the studio remits), and **grand total**.
 
 ## Access Rules
+
 - Studio admin (`view_all_payments`): all instructors; may filter by `instructor_id`.
-- Instructor (`view_own_payments`): rows where `us_payments.instructor_id` is their own user ID only.
+- Instructor (`view_own_payments`): always scoped to their own user ID; the
+  instructor filter is hidden and any requested `instructor_id` is overridden.
 - Export requires `export_payments` and is scoped to the same rows the caller may view.
 
 ## Admin Interface
-**Payments** in wp-admin:
-- Month picker (defaults to the current month) and, for studio admin, an instructor filter
-- A table of payments with a monthly total
-- An **Export** button that downloads the filtered rows as CSV
 
-## REST API
-| Method | Endpoint                                       | Permission           |
-|--------|------------------------------------------------|----------------------|
-| `GET`  | `/wp-json/us-scheduler/v1/payments`            | `view_own_payments` or `view_all_payments` |
-| `GET`  | `/wp-json/us-scheduler/v1/payments/export`     | `export_payments`    |
+**Payment Report** in wp-admin (top-level menu, gated on `export_payments` so
+instructors — who lack `manage_billing` — can reach it):
 
-Query params: `month` (`YYYY-MM`, required), `instructor_id` (optional; ignored for
-instructors, who are always scoped to themselves). `GET /payments/export` returns
-`text/csv` with a `Content-Disposition` attachment header.
+- Month picker (defaults to the current month) and, for studio admin, an
+  instructor filter
+- A summary line of HST collected / subtotal / total collected
+- A table of paid payments with a totals footer
+- An **Export CSV** button that downloads the filtered rows (plus a totals row)
+
+## Export
+
+CSV export is served by an `admin-post.php` handler
+(`admin_post_usc_export_payments`) rather than a REST route, so the browser
+downloads it directly with a nonce-protected link. It honours the same `month`
+and `instructor_id` query params as the page and returns `text/csv` with a
+`Content-Disposition: attachment` header. Instructor requests are scoped to
+their own rows regardless of `instructor_id`.
 
 ## Implementation
-- Report controller: `Unsupervised\Schedular\Payment\PaymentReportController`
-- CSV exporter: `Unsupervised\Schedular\Payment\PaymentExporter`
-- Report query: `Unsupervised\Schedular\Payment\PaymentRepository::report()`
+
+- Report aggregator (pure totals + CSV): `Unsupervised\Schedular\Payment\PaymentReport`
+- Report controller (page + export): `Unsupervised\Schedular\Payment\PaymentReportController`
+- Report query: `Unsupervised\Schedular\Payment\PaymentRepository::findPaidBetween()`
+- Template: `templates/admin/payment-report.php`
+- Menu + `admin_post` wiring: `Unsupervised\Schedular\AdminMenu`
 
 ## Tests
-- `tests/Unit/Payment/PaymentReportControllerTest.php`
-- `tests/Unit/Payment/PaymentExporterTest.php`
+
+- `tests/Unit/Payment/PaymentReportTest.php` — totals and CSV rendering
+- `tests/Unit/Payment/PaymentRepositoryTest.php` — `findPaidBetween` query

docs/features/payments.md

@@ -28,6 +28,22 @@ page (`manage_billing`, studio admin only):
 | `us_stripe_secret_key`       | Stripe secret key                      |
 | `us_stripe_mode`             | `test` or `live`                       |
 | `us_currency`                | Default ISO 4217 currency, e.g. `CAD`  |
+| `us_etransfer_email`         | Studio-default e-transfer destination  |
+| `us_hst_rate`                | Default HST/tax percentage, e.g. `13`  |
+
+## HST / Tax
+
+A studio-default **HST rate** (percentage) is configured on **Studio Settings**
+(`us_hst_rate`, `manage_billing`). At booking the rate is **frozen onto the
+payment** (`us_payments.tax_rate`) and the tax is computed against the pre-tax
+subtotal (`tax_amount = round(amount × rate / 100, 2)`). The billed total is
+`amount + tax_amount` (`Payment::total()`). Comped registrations are never taxed
+(rate and amount are 0).
+
+The rate is overridable **per booking** on **My Lessons** (instructor) while the
+payment is still unpaid; saving recomputes `tax_amount` from the current
+subtotal (`PaymentRepository::updateTax`). Receipts break out subtotal, HST, and
+total when tax applies.
 
 ## Per-Student Billing Method
 Each student's billing method is stored in user meta `us_payment_method`, set by the
@@ -66,6 +82,8 @@ After booking, the destination on a payment can be corrected per booking:
 | `currency`                 | VARCHAR(3)       | ISO 4217, e.g. `CAD`                                  |
 | `method`                   | VARCHAR(20)      | `card` / `etransfer` / `comp`                         |
 | `status`                   | VARCHAR(20)      | `pending` / `paid` / `failed` / `refunded`            |
+| `tax_rate`                 | DECIMAL(5,2)     | HST rate % frozen at booking; editable until paid     |
+| `tax_amount`               | DECIMAL(10,2)    | Computed tax in dollars (`amount × tax_rate / 100`)   |
 | `etransfer_email`          | VARCHAR(191)     | Frozen e-transfer destination; editable until confirmed |
 | `stripe_payment_intent_id` | VARCHAR(255)     | Stripe PaymentIntent id; NULL for e-transfer / comp   |
 | `receipt_number`           | VARCHAR(50)      | Sequential receipt id; set when `paid`                |