Add e-transfer destination email (studio default + offering/booking overrides)

The e-transfer destination is resolved at booking time (offering override ->
studio default) and frozen onto the payment, so each record keeps where the
student was directed. It can then be corrected per booking.

- StudioSettings: us_etransfer_email option + a Default e-transfer email field
  on the Studio Settings page.
- Offering: etransfer_email column/field (instructor override) across VO, repo,
  REST endpoint, admin controller, and form.
- Payment: etransfer_email column on the payment (frozen record) +
  PaymentRepository::updateEtransferEmail; PaymentService freezes it from the
  offering override or studio default at creation; booking/enrolment pass the
  offering override.
- My Lessons: instructors edit the e-transfer email per pending lesson payment
  (ownership-checked).
- Payments queue: studio admin can correct the email at confirmation (for when
  a student sends it to the wrong place).
- Docs updated.

Tests: Payment/Offering rows + PaymentService freezing. composer test (148),
cs, and PHPStan level 6 all pass.

Refs #7

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

src/Booking/BookingEndpoint.php

@@ -157,7 +157,7 @@ class BookingEndpoint {
 		$this->gate->record( PolicyAcceptance::REG_LESSON, $anchorId, $studentId, $offeringId, $answers, $acceptedVersionIds, $this->clientIp() );
 
 		if ( null !== $offering && $offering->price > 0.0 ) {
-			$this->payments->createForRegistration( Payment::REG_LESSON, $anchorId, $studentId, $slot->instructorId, $offering->price, $offering->currency );
+			$this->payments->createForRegistration( Payment::REG_LESSON, $anchorId, $studentId, $slot->instructorId, $offering->price, $offering->currency, $offering->etransferEmail );
 		}
 
 		return new \WP_REST_Response(

src/Booking/LessonController.php

@@ -4,17 +4,24 @@ declare(strict_types=1);
 namespace Unsupervised\Schedular\Booking;
 
 use Unsupervised\Schedular\Auth\RoleManager;
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\PaymentRepository;
 
 class LessonController {
 
-	public function __construct( private BookingRepository $repository ) {}
+	public function __construct(
+		private BookingRepository $repository,
+		private PaymentRepository $payments,
+	) {}
 
 	public function renderAdminDashboard(): void {
 		if ( ! current_user_can( RoleManager::CAP_VIEW_ALL_LESSONS ) ) {
 			wp_die( esc_html__( 'You do not have permission to view this page.', 'unsupervised-schedular' ) );
 		}
 
-		$lessons = $this->repository->findAllUpcoming();
+		$this->handleEtransferUpdate( false );
+
+		$rows = array_map( fn( Lesson $lesson ): array => $this->row( $lesson ), $this->repository->findAllUpcoming() );
 
 		include USC_PLUGIN_DIR . 'templates/admin/lessons.php';
 	}
@@ -24,8 +31,60 @@ class LessonController {
 			wp_die( esc_html__( 'You do not have permission to view lessons.', 'unsupervised-schedular' ) );
 		}
 
-		$lessons = $this->repository->findUpcomingForInstructor( get_current_user_id() );
+		$this->handleEtransferUpdate( true );
+
+		$rows = array_map( fn( Lesson $lesson ): array => $this->row( $lesson ), $this->repository->findUpcomingForInstructor( get_current_user_id() ) );
 
 		include USC_PLUGIN_DIR . 'templates/admin/lessons.php';
 	}
+
+	/**
+	 * Handle a per-lesson e-transfer email override. When $onlyOwn, the payment
+	 * must belong to the current instructor.
+	 */
+	private function handleEtransferUpdate( bool $onlyOwn ): void {
+		if ( ! isset( $_POST['usc_action'] ) || ! check_admin_referer( 'usc_lesson_action' ) ) {
+			return;
+		}
+
+		// phpcs:disable WordPress.Security.NonceVerification.Missing -- nonce checked above.
+		if ( 'set_etransfer' !== sanitize_key( wp_unslash( $_POST['usc_action'] ?? '' ) ) ) {
+			return;
+		}
+
+		$paymentId = absint( $_POST['payment_id'] ?? 0 );
+		$email     = sanitize_email( wp_unslash( $_POST['etransfer_email'] ?? '' ) );
+		// phpcs:enable WordPress.Security.NonceVerification.Missing
+
+		if ( $paymentId <= 0 ) {
+			return;
+		}
+
+		$payment = $this->payments->findById( $paymentId );
+		if ( null !== $payment && ( ! $onlyOwn || get_current_user_id() === $payment->instructorId ) ) {
+			$this->payments->updateEtransferEmail( $paymentId, '' !== $email ? $email : null );
+		}
+	}
+
+	/**
+	 * Build a display row for a lesson, including its e-transfer payment override.
+	 *
+	 * @return array<string, mixed>
+	 */
+	private function row( Lesson $lesson ): array {
+		$student    = get_userdata( $lesson->studentId );
+		$instructor = get_userdata( $lesson->instructorId );
+		$payment    = null !== $lesson->paymentId ? $this->payments->findById( $lesson->paymentId ) : null;
+
+		return [
+			'student'            => $student ? $student->display_name : (string) $lesson->studentId,
+			'instructor'         => $instructor ? $instructor->display_name : (string) $lesson->instructorId,
+			'slot_id'            => (int) $lesson->slotId,
+			'status'             => $lesson->status,
+			'notes'              => $lesson->notes ?? '',
+			'payment_id'         => $payment ? (int) $payment->id : 0,
+			'etransfer_email'    => $payment ? (string) $payment->etransferEmail : '',
+			'etransfer_editable' => null !== $payment && Payment::METHOD_ETRANSFER === $payment->method && ! $payment->isPaid(),
+		];
+	}
 }