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

templates/admin/student-detail.php

@@ -14,6 +14,9 @@ if (! defined('ABSPATH')) {
  * @var list<array{question: string, answer: string, required: bool}> $registrationInfo
  * @var list<array{question: string, answer: string, context: string}> $intake
  * @var list<array{created_at: string, context: string, method: string, status: string, amount: float, tax_amount: float, total: float, currency: string, receipt: string}> $payments
+ * @var list<array{created_at: string, amount: float, remaining: float, currency: string, reason: string, status: string}> $credits
+ * @var float  $creditBalance
+ * @var string $creditCurrency
  * @var string $backUrl
  * @var bool   $canBilling
  * @var string $billingOverride
@@ -241,6 +244,42 @@ $renderLessons = static function (array $rows, bool $withActions = false): void
     <?php endif; ?>
 
     <?php if ($canBilling) : ?>
+        <h2><?php esc_html_e('Account credit', 'unsupervised-schedular'); ?></h2>
+        <p>
+            <?php
+            printf(
+                /* translators: %s: available credit balance, e.g. "45.00 CAD" */
+                esc_html__('Available balance: %s', 'unsupervised-schedular'),
+                '<strong>' . esc_html(number_format_i18n($creditBalance, 2) . ' ' . $creditCurrency) . '</strong>'
+            );
+            ?>
+            <span class="description"><?php esc_html_e('Credit from cancelled paid lessons is applied automatically to upcoming scheduled billing.', 'unsupervised-schedular'); ?></span>
+        </p>
+        <?php if (! empty($credits)) : ?>
+            <table class="wp-list-table widefat fixed striped">
+                <thead>
+                    <tr>
+                        <th><?php esc_html_e('Date', 'unsupervised-schedular'); ?></th>
+                        <th><?php esc_html_e('Reason', 'unsupervised-schedular'); ?></th>
+                        <th><?php esc_html_e('Amount', 'unsupervised-schedular'); ?></th>
+                        <th><?php esc_html_e('Remaining', 'unsupervised-schedular'); ?></th>
+                        <th><?php esc_html_e('Status', 'unsupervised-schedular'); ?></th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <?php foreach ($credits as $credit) : ?>
+                        <tr>
+                            <td><?php echo esc_html($credit['created_at'] !== '' ? (string) mysql2date('M j, Y g:i A', $credit['created_at']) : '—'); ?></td>
+                            <td><?php echo esc_html($credit['reason']); ?></td>
+                            <td><?php echo esc_html(number_format_i18n($credit['amount'], 2) . ' ' . $credit['currency']); ?></td>
+                            <td><?php echo esc_html(number_format_i18n($credit['remaining'], 2) . ' ' . $credit['currency']); ?></td>
+                            <td><?php echo esc_html($credit['status']); ?></td>
+                        </tr>
+                    <?php endforeach; ?>
+                </tbody>
+            </table>
+        <?php endif; ?>
+
         <h2><?php esc_html_e('Payment history', 'unsupervised-schedular'); ?></h2>
         <?php if (empty($payments)) : ?>
             <p><?php esc_html_e('None.', 'unsupervised-schedular'); ?></p>