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/Credit.php

@@ -0,0 +1,79 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Payment;
+
+use Unsupervised\Schedular\Val;
+
+/**
+ * A studio credit held on a student's account — money already paid for a lesson
+ * that was later cancelled. Credits are consumed against future scheduled-billing
+ * charges (weekly / monthly) before the student is asked to pay, oldest first.
+ */
+class Credit {
+
+	public const STATUS_AVAILABLE = 'available';
+	public const STATUS_CONSUMED  = 'consumed';
+
+	/**
+	 * All valid credit statuses.
+	 *
+	 * @var list<string>
+	 */
+	public const VALID_STATUSES = [ self::STATUS_AVAILABLE, self::STATUS_CONSUMED ];
+
+	public function __construct(
+		public readonly int $studentId,
+		public readonly float $amount,
+		public readonly float $remaining,
+		public readonly string $currency = 'CAD',
+		public readonly ?int $sourcePaymentId = null,
+		public readonly ?int $sourceLessonId = null,
+		public readonly ?string $reason = null,
+		public readonly string $status = self::STATUS_AVAILABLE,
+		public readonly ?string $createdAt = null,
+		public readonly ?string $updatedAt = null,
+		public readonly ?int $id = null,
+	) {}
+
+	public static function fromRow( \stdClass $row ): self {
+		return new self(
+			studentId:       Val::int( $row->student_id ),
+			amount:          Val::float( $row->amount ),
+			remaining:       Val::float( $row->remaining ),
+			currency:        Val::string( $row->currency ),
+			sourcePaymentId: Val::intOrNull( $row->source_payment_id ?? null ),
+			sourceLessonId:  Val::intOrNull( $row->source_lesson_id ?? null ),
+			reason:          Val::stringOrNull( $row->reason ?? null ),
+			status:          Val::string( $row->status ),
+			createdAt:       Val::stringOrNull( $row->created_at ?? null ),
+			updatedAt:       Val::stringOrNull( $row->updated_at ?? null ),
+			id:              Val::int( $row->id ),
+		);
+	}
+
+	public function isAvailable(): bool {
+		return self::STATUS_AVAILABLE === $this->status && $this->remaining > 0.0;
+	}
+
+	/**
+	 * Returns a plain array representation of the credit.
+	 *
+	 * @return array<string, mixed>
+	 */
+	public function toArray(): array {
+		return [
+			'id'                => $this->id,
+			'student_id'        => $this->studentId,
+			'amount'            => $this->amount,
+			'remaining'         => $this->remaining,
+			'currency'          => $this->currency,
+			'source_payment_id' => $this->sourcePaymentId,
+			'source_lesson_id'  => $this->sourceLessonId,
+			'reason'            => $this->reason,
+			'status'            => $this->status,
+			'created_at'        => $this->createdAt,
+			'updated_at'        => $this->updatedAt,
+		];
+	}
+}