Credit students for cancelled paid lessons

Cancelling a lesson that was already paid for now credits the student
that money instead of leaving it as a manual refund, and the daily
scheduled-billing scan applies any available credit against their due
charges before emailing the notice.

- New us_credits ledger + us_payments.credit_applied column (Payment::netDue).
- PaymentService::creditForCancelledLesson issues a per-lesson share of the
  covering payment's total; wired into all three cancel paths (student
  self-cancel, instructor status update, admin student-detail cancel).
- PaymentService::applyCredits draws credit down FIFO across a run's charges,
  marking a fully-covered charge paid-by-credit; the notice shows the credit
  applied and reduced total, and the admin queue shows net due.
- Student detail page shows a student's credit balance and history.

Ships as part of the unreleased 1.2.0 (same release as scheduled billing).

Tests: composer test (585), composer lint, composer cs all pass.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

src/Payment/Payment.php

@@ -44,6 +44,7 @@ class Payment {
 		public readonly string $status = self::STATUS_PENDING,
 		public readonly float $taxRate = 0.0,
 		public readonly float $taxAmount = 0.0,
+		public readonly float $creditApplied = 0.0,
 		public readonly ?string $dueDate = null,
 		public readonly ?string $periodKey = null,
 		public readonly ?string $noticeBatch = null,
@@ -68,6 +69,7 @@ class Payment {
 			status:                Val::string( $row->status ),
 			taxRate:               Val::float( $row->tax_rate ),
 			taxAmount:             Val::float( $row->tax_amount ),
+			creditApplied:         Val::float( $row->credit_applied ?? 0 ),
 			dueDate:               Val::stringOrNull( $row->due_date ?? null ),
 			periodKey:             Val::stringOrNull( $row->period_key ?? null ),
 			noticeBatch:           Val::stringOrNull( $row->notice_batch ?? null ),
@@ -101,6 +103,14 @@ class Payment {
 		return round( $this->amount + $this->taxAmount, 2 );
 	}
 
+	/**
+	 * What the student still owes after any account credit applied to this payment.
+	 * The full `total()` less `creditApplied`, floored at zero.
+	 */
+	public function netDue(): float {
+		return round( max( 0.0, $this->total() - $this->creditApplied ), 2 );
+	}
+
 	/**
 	 * Minimal payment info embedded in registration-creation responses: enough
 	 * for the front end to decide whether (and how) to run the payment step.
@@ -132,6 +142,8 @@ class Payment {
 			'tax_rate'          => $this->taxRate,
 			'tax_amount'        => $this->taxAmount,
 			'total'             => $this->total(),
+			'credit_applied'    => $this->creditApplied,
+			'net_due'           => $this->netDue(),
 			'currency'          => $this->currency,
 			'method'            => $this->method,
 			'status'            => $this->status,