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