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>

src/Payment/PaymentReport.php

@@ -0,0 +1,105 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Payment;
+
+/**
+ * Pure aggregator over a set of paid-payment display rows: produces the column
+ * totals (subtotal, HST collected, grand total) and a CSV rendering. Building
+ * the rows (name lookups, filtering) is the controller's job — this class does
+ * no I/O so it stays trivially testable.
+ */
+class PaymentReport {
+
+	/**
+	 * Build a report over already-resolved display rows.
+	 *
+	 * @param list<array{date: string, student: string, instructor: string, method: string, status: string, amount: float, tax_rate: float, tax_amount: float, total: float}> $rows
+	 */
+	public function __construct( private array $rows ) {}
+
+	/**
+	 * The report's display rows.
+	 *
+	 * @return list<array{date: string, student: string, instructor: string, method: string, status: string, amount: float, tax_rate: float, tax_amount: float, total: float}>
+	 */
+	public function rows(): array {
+		return $this->rows;
+	}
+
+	public function count(): int {
+		return count( $this->rows );
+	}
+
+	public function totalAmount(): float {
+		return round( array_sum( array_column( $this->rows, 'amount' ) ), 2 );
+	}
+
+	/**
+	 * Total HST collected across all rows — the figure the studio remits.
+	 */
+	public function totalTax(): float {
+		return round( array_sum( array_column( $this->rows, 'tax_amount' ) ), 2 );
+	}
+
+	public function grandTotal(): float {
+		return round( array_sum( array_column( $this->rows, 'total' ) ), 2 );
+	}
+
+	/**
+	 * Render the report as CSV, including a trailing totals row.
+	 */
+	public function toCsv(): string {
+		$lines = [];
+
+		$lines[] = $this->csvLine(
+			[ 'Date', 'Student', 'Instructor', 'Method', 'Status', 'Subtotal', 'HST Rate', 'HST', 'Total' ]
+		);
+
+		foreach ( $this->rows as $row ) {
+			$lines[] = $this->csvLine(
+				[
+					$row['date'],
+					$row['student'],
+					$row['instructor'],
+					$row['method'],
+					$row['status'],
+					number_format( $row['amount'], 2, '.', '' ),
+					number_format( $row['tax_rate'], 2, '.', '' ),
+					number_format( $row['tax_amount'], 2, '.', '' ),
+					number_format( $row['total'], 2, '.', '' ),
+				]
+			);
+		}
+
+		$lines[] = $this->csvLine(
+			[
+				'Totals',
+				'',
+				'',
+				'',
+				'',
+				number_format( $this->totalAmount(), 2, '.', '' ),
+				'',
+				number_format( $this->totalTax(), 2, '.', '' ),
+				number_format( $this->grandTotal(), 2, '.', '' ),
+			]
+		);
+
+		return implode( "\n", $lines ) . "\n";
+	}
+
+	/**
+	 * Format one CSV record, quoting fields and escaping embedded quotes.
+	 *
+	 * @param list<string> $fields
+	 */
+	private function csvLine( array $fields ): string {
+		$escaped = array_map(
+			static fn( string $field ): string => '"' . str_replace( '"', '""', $field ) . '"',
+			$fields
+		);
+
+		return implode( ',', $escaped );
+	}
+}