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]>

tests/Unit/Booking/BookingEndpointTest.php

@@ -48,6 +48,9 @@ class BookingEndpointTest extends TestCase
         $this->payments     = Mockery::mock(PaymentService::class);
         $this->settings     = Mockery::mock(StudioSettings::class);
         $this->settings->shouldReceive('cancellationCutoffHours')->andReturn(24)->byDefault();
+        // Crediting a cancelled paid lesson is exercised in dedicated tests; other
+        // cancellation paths simply allow the call.
+        $this->payments->shouldReceive('creditForCancelledLesson')->andReturn(null)->byDefault();
 
         $this->endpoint = new BookingEndpoint(
             $this->availability,
@@ -472,6 +475,24 @@ class BookingEndpointTest extends TestCase
         self::assertSame(Lesson::STATUS_CANCELLED, $result->get_data()['status']);
     }
 
+    public function testCancelCreditsThePaidLesson(): void
+    {
+        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_PENDING, paymentId: 12, id: 77);
+        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
+        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
+        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CANCELLED)->once()->andReturn(true);
+        $this->availability->shouldReceive('release')->with(10)->once()->andReturn(true);
+        $this->payments->shouldReceive('voidPending')->with(12)->once();
+
+        // The cancelled lesson (the value object, so its payment_id is intact) is
+        // handed to the credit path.
+        $this->payments->shouldReceive('creditForCancelledLesson')
+            ->once()
+            ->with(Mockery::on(static fn (Lesson $l): bool => $l->id === 77 && $l->paymentId === 12));
+
+        $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));
+    }
+
     public function testCancelWithinStudioCutoffIsRejected(): void
     {
         // Now (2026-06-01 10:00) is only 24h before a slot at 2026-06-02 10:00,