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/Auth/StudentHistory.php

@@ -3,6 +3,8 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Payment\Credit;
+use Unsupervised\Schedular\Payment\CreditRepository;
 use Unsupervised\Schedular\Payment\Payment;
 use Unsupervised\Schedular\Payment\PaymentRepository;
 use Unsupervised\Schedular\Policy\AcceptanceRepository;
@@ -27,6 +29,7 @@ class StudentHistory {
 		private AnswerRepository $answers,
 		private QuestionRepository $questions,
 		private PaymentRepository $payments,
+		private CreditRepository $credits,
 	) {}
 
 	/**
@@ -129,6 +132,34 @@ class StudentHistory {
 		);
 	}
 
+	/**
+	 * The student's total unused credit balance (from cancelled paid lessons),
+	 * applied automatically against future scheduled-billing charges.
+	 */
+	public function creditBalance( int $studentId ): float {
+		return $this->credits->availableBalance( $studentId );
+	}
+
+	/**
+	 * Every credit the student has been issued, newest first, with the amount, what
+	 * remains, and its state.
+	 *
+	 * @return list<array{created_at: string, amount: float, remaining: float, currency: string, reason: string, status: string}>
+	 */
+	public function credits( int $studentId ): array {
+		return array_map(
+			static fn( Credit $credit ): array => [
+				'created_at' => $credit->createdAt ?? '',
+				'amount'     => $credit->amount,
+				'remaining'  => $credit->remaining,
+				'currency'   => $credit->currency,
+				'reason'     => $credit->reason ?? '—',
+				'status'     => $credit->status,
+			],
+			$this->credits->findByStudent( $studentId )
+		);
+	}
+
 	/**
 	 * Human label for a polymorphic registration target.
 	 */