Add payments foundation (e-transfer/comp, Stripe config, receipts)

Implements the payments foundation for #7. Without Stripe credentials
everything works on e-transfer (pending payment confirmed by a studio
admin); when Stripe keys are configured the default flips to credit card.
Per-student override (card/etransfer/comp) is set on the student detail.

- Schema: us_payments (amount DECIMAL dollars, method, status, receipt,
  stripe intent id).
- src/Payment/: Payment VO, PaymentRepository, StudioSettings (Stripe
  options + isStripeConfigured + settings page), BillingMethodResolver
  (per-student override; default card if configured else etransfer),
  ReceiptMailer, PaymentService (create at registration, link payment_id,
  comp->paid+confirm, markPaid->confirm+receipt), PaymentController
  (e-transfer confirmation queue), PaymentEndpoint (PATCH /payments/{id}).
- Booking + enrolment create the payment from the offering price; comp
  auto-confirms the lesson; setPaymentId on both repositories.
- Admin: Studio Settings + Payments menus (manage_billing); per-student
  billing method on the student detail page.
- Docs: payments.md + README updated.

Deferred to a follow-up: the live Stripe card charge (PaymentIntent +
Stripe.js Elements + webhook + stripe/stripe-php). Until then a card
payment is created pending and confirmed like an e-transfer.

Tests: tests/Unit/Payment/ (VO, repository, resolver, service, mailer).
composer test (147), cs, and PHPStan level 6 all pass.

Refs #7

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

src/Payment/PaymentService.php

@@ -0,0 +1,103 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Payment;
+
+use Unsupervised\Schedular\Booking\BookingRepository;
+use Unsupervised\Schedular\Booking\Lesson;
+use Unsupervised\Schedular\GroupClass\EnrollmentRepository;
+
+/**
+ * Orchestrates payment creation and confirmation across the payment ledger and
+ * the registrations (lessons / enrolments) they pay for.
+ */
+class PaymentService {
+
+	public function __construct(
+		private PaymentRepository $payments,
+		private BillingMethodResolver $resolver,
+		private ReceiptMailer $mailer,
+		private BookingRepository $bookings,
+		private EnrollmentRepository $enrollments,
+	) {}
+
+	/**
+	 * Create the payment for a new registration and link it. Comped students are
+	 * marked paid and confirmed immediately; everyone else gets a pending payment
+	 * (card via Stripe — coming soon; e-transfer confirmed manually). Returns null
+	 * when the registration has no price to charge.
+	 */
+	public function createForRegistration( string $type, int $registrationId, int $studentId, int $instructorId, float $amount, string $currency ): ?Payment {
+		if ( $amount <= 0.0 ) {
+			return null;
+		}
+
+		$method = $this->resolver->resolve( $studentId );
+		$status = Payment::METHOD_COMP === $method ? Payment::STATUS_PAID : Payment::STATUS_PENDING;
+
+		$id = $this->payments->insert(
+			new Payment(
+				studentId:        $studentId,
+				instructorId:     $instructorId,
+				registrationType: $type,
+				registrationId:   $registrationId,
+				amount:           $amount,
+				currency:         $currency,
+				method:           $method,
+				status:           $status,
+			)
+		);
+
+		$this->linkPayment( $type, $registrationId, $id );
+
+		if ( Payment::STATUS_PAID === $status ) {
+			$this->finalizePaid( $id, $type, $registrationId, $studentId );
+		}
+
+		return $this->payments->findById( $id );
+	}
+
+	/**
+	 * Studio-admin confirmation that a pending payment (e-transfer) was received.
+	 * Marks it paid, confirms the registration, and emails the receipt.
+	 */
+	public function markPaid( int $paymentId ): bool {
+		$payment = $this->payments->findById( $paymentId );
+		if ( null === $payment ) {
+			return false;
+		}
+		if ( $payment->isPaid() ) {
+			return true;
+		}
+
+		$this->finalizePaid( $paymentId, $payment->registrationType, $payment->registrationId, $payment->studentId );
+
+		return true;
+	}
+
+	private function finalizePaid( int $paymentId, string $type, int $registrationId, int $studentId ): void {
+		$this->payments->markPaid( $paymentId, 'USC-' . $paymentId );
+		$this->confirmRegistration( $type, $registrationId );
+
+		$paid = $this->payments->findById( $paymentId );
+		$user = get_userdata( $studentId );
+		if ( null !== $paid && $this->mailer->send( $paid, $user instanceof \WP_User ? $user : null ) ) {
+			$this->payments->markReceiptSent( $paymentId );
+		}
+	}
+
+	private function confirmRegistration( string $type, int $registrationId ): void {
+		if ( Payment::REG_LESSON === $type ) {
+			$this->bookings->updateStatus( $registrationId, Lesson::STATUS_CONFIRMED );
+		}
+		// Group enrolments are already `active`; no status change on payment.
+	}
+
+	private function linkPayment( string $type, int $registrationId, int $paymentId ): void {
+		if ( Payment::REG_LESSON === $type ) {
+			$this->bookings->setPaymentId( $registrationId, $paymentId );
+		} elseif ( Payment::REG_ENROLLMENT === $type ) {
+			$this->enrollments->setPaymentId( $registrationId, $paymentId );
+		}
+	}
+}